Buddy 宠物系统在 OpenClaw 上复刻 — 可行性评估

任务ID: ciallo-20260403-002 | 调研日期: 2026-04-03

---

一、GitHub 项目分析

项目	语言	Stars	核心功能	OpenClaw 适配难度
claude-code-pet-system-analysis	Python	23	宠物系统逆向分析文档	❌ 纯分析，无代码可复用
buddy-gacha	TypeScript/Bun	3	暴力刷宠（需 Bun.hash）	❌ 强耦合 Claude Code 配置
buddy-rpg	JavaScript/Node.js	2	RPG 成长系统 + 成就 + 战斗	✅ 最适合适配
clawd-on-desk	JavaScript/Electron	613	桌面宠物（多agent支持）	⚠️ 桌面端，需重构

---

二、各项目详细评估

1. claude-code-pet-system-analysis ⚠️ 参考价值

• 纯分析文档，包含 18 种宠物图鉴、稀有度算法、进化系统
• 可复用：宠物种类设计、稀有度权重、属性系统
• 不可复用：无实际代码

2. buddy-gacha ❌ 不适配

• 核心逻辑依赖 Bun.hash()（wyhash）+ SplitMix32 PRNG
• 攻击向量是替换 ~/.claude.json 中的 userID
• 强耦合 Claude Code 的 friend-2026-401 SALT
• 无法脱离 Claude Code 环境运行

3. buddy-rpg ✅ 推荐基础

• 零依赖，纯 Node.js 18+，可在 VPS 运行
• 完整 RPG 系统：
  • 5 个成长阶段（Hatchling → Mythic）
  • 6 项属性（debugging/patience/chaos/wisdom/snark + XP）
  • 15 个成就
  • 战斗系统
  • 连击 streak 加成
• 数据存储：~/.buddy-rpg.json，可轻松改为每 agent 独立文件
• 已有 Claude Code hooks：session-start/end、tool-use、tool-failure
• 可复用模块：
  • lib/engine.js — XP/等级/成就核心引擎
  • lib/card.js — 宠物卡牌渲染（ASCII，需改飞书）
  • hooks/ — 事件监听框架
• 需要改造：
  • 事件源：从 Claude Code hooks → OpenClaw 事件
  • 渲染：从终端 ANSI → 飞书消息/卡片
  • 存储：单文件 → 多 agent 分离

4. clawd-on-desk ⚠️ 参考价值高但平台不对

• 613 stars，项目成熟度最高
• 已支持 5 种 agent（Claude Code/Codex/Copilot/Gemini/Cursor）
• 有完整的状态机：idle/thinking/typing/building/juggling 等 12 种动画
• 支持 SSH 远程模式（通过 HTTP hook 转发）
• 问题：Electron 桌面应用，我们的场景是 Linux VPS + 飞书
• 可复用：hook 架构设计思路、多 agent 状态管理
• 不可复用：Electron UI、动画系统、桌面交互

---

三、推荐方案

方案：基于 buddy-rpg 引擎 + 飞书集成

┌─────────────────────────────────────────────────┐
│                  OpenClaw Gateway                │
│                                                  │
│  Agent 事件 ──→ 钩子层 ──→ Pet Engine ──→ 存储   │
│     (tool_use,    │         (buddy-rpg    (~/.   │
│      session,     │          引擎改造)    openclaw│
│      message)     │                       /pets/ │
│                   │                              │
│                   └──→ 飞书卡片渲染              │
│                         (image/card)             │
└─────────────────────────────────────────────────┘

核心模块设计

1. Pet Engine（复用 buddy-rpg lib/engine.js）

• 保持 XP/等级/属性/成就/战斗核心逻辑
• 事件源改为 OpenClaw 钩子：
  • tool_use → 对应 buddy-rpg 的 tool_success_* 事件
  • tool_failure → 对应 tool_failure
  • session_start/end → 对应 session 生命周期
  • message_received → 新增：飞书消息互动（pet/feed 命令）

2. 数据存储

~/.openclaw/pets/
├── ny.json      # 宁姚的宠物
├── cpa.json     # 陈平安的宠物
├── xr.json      # 小任的宠物
├── pq.json      # 裴钱的宠物
├── ns.json      # 暖树的宠物
└── zml.json     # 周米粒的宠物

每个 JSON 结构（复用 buddy-rpg 数据格式）：

{
  "pet": {
    "name": "小剑灵",
    "species": "dragon",
    "rarity": "rare",
    "xp": 3200,
    "stats": { "debugging": 45, "patience": 30, "chaos": 20, "wisdom": 35, "snark": 15 }
  },
  "streak": { "current": 7, "best": 15, "lastActive": "2026-04-02" },
  "session": { "totalSessions": 89, "todayCount": 2 },
  "achievements": [...],
  "history": [...]
}

3. 飞书展示（关键差异化）

展示方式	适用场景	复杂度
飞书富文本卡片	宠物状态卡、升级通知、成就解锁	⭐⭐ 中等
生成宠物图片	飞书消息发送 PNG（用 canvas/node-canvas 生成）	⭐⭐⭐ 较高
纯文本 ASCII	简单状态查看	⭐ 低
组合方案	卡片+图片	⭐⭐⭐ 推荐

推荐组合方案：

• 日常状态 → 飞书 Interactive Card（JSON 卡片，含属性条、等级、XP 进度）
• 升级/成就 → 飞书卡片 + 通知消息
• 宠物形象 → 用 canvas 或预渲染图片生成小宠物 PNG

4. 交互方式

在飞书群聊中通过命令触发：

• /pet status → 查看宠物状态卡
• /pet feed → 喂食（+3 XP）
• /pet battle @xxx → 与另一只宠物对战
• /pet achievements → 成就列表
• 每次 agent 执行工具 → 自动累加 XP（后台）

---

四、能不能每个 agent 有自己的宠物？

✅ 完全可以。 这是最自然的方案。

• 每个 agent（ny/cpa/xr/pq/ns/zml）在 OpenClaw 中有独立身份
• 事件监听时按 agent_id 分离 → 写入对应 JSON 文件
• 宠物可以有不同的 species/rarity（首次激活时随机生成或用户选择）
• agent 间的宠物可以互动（跨群战斗、排行榜）

---

五、工作量估计

模块	工作量	说明
Pet Engine 改造	2-3 天	复用 engine.js，改造事件源接口
OpenClaw 钩子集成	1-2 天	编写 OpenClaw 事件到宠物事件的映射层
数据存储（多 agent）	0.5 天	文件路径分离，加锁（并发写）
飞书卡片渲染	2-3 天	替换 card.js ANSI 渲染为飞书 Interactive Card JSON
宠物图片生成（可选）	2-3 天	canvas 生成宠物 PNG，或用预置素材拼接
命令交互	1 天	/pet 系列命令解析
测试 + 部署	1 天	6 个 agent 测试 + VPS 部署
合计	10-15 天	单人开发，不含图片生成可缩至 7-10 天

---

六、风险与注意事项

风险	影响	缓解措施
OpenClaw 事件系统可能没有完整的 tool_use 钩子	宠物 XP 来源受限	优先用 message/session 事件，tool_use 可后续加
飞书卡片自定义程度有限	复杂 UI 可能受限	组合使用卡片+图片
多 agent 并发写文件	数据损坏	加文件锁（proper-lockfile）或用 SQLite
鑫哥可能想一出是一出	需求变更	模块化设计，宠物引擎独立于展示层

---

七、结论

✅ 可行，推荐实施。

• 最容易集成的项目：buddy-rpg — 零依赖、纯 Node.js、核心引擎完整
• 数据存储：每 agent 独立 JSON 文件（~/.openclaw/pets/{agent_id}.json）
• 每 agent 有自己的宠物：✅ 天然支持
• 飞书展示：飞书 Interactive Card + 可选宠物 PNG 图片
• 工作量：7-15 天（取决于图片生成是否做）

建议先做 MVP：Pet Engine + 飞书卡片 + 基础命令 → 3-5 天出效果 → 再迭代图片和战斗系统。

---

归档时间: 2026-04-14
来源: /root/.openclaw/workspace-ny/research/buddy-pet-feasibility.md